/*!
 * \file size_policies.hpp
 * \brief 大小策略
 *
 * \details 此文件包含thread_pool的大小策略。
 *          
 *          大小策略控制线程池中工作线程的数量。
 *          
 *          提供的组件包括：
 *          - empty_controller：不提供功能的大小策略控制器
 *          - resize_controller：允许调整大小的控制器
 *          - static_size：保持线程数量的大小策略
 *          
 *          这些策略为线程池提供了灵活的线程数量管理机制，
 *          从静态固定大小到动态调整大小的各种选择。
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */

#ifndef THREADPOOL_SIZE_POLICIES_HPP_INCLUDED
#define THREADPOOL_SIZE_POLICIES_HPP_INCLUDED

/// threadpool命名空间包含线程池和相关实用类
namespace boost { namespace threadpool
{

  /*!
   * \brief 不提供功能的大小策略控制器
   *
   * \details 这是一个空的控制器实现，不提供任何线程池大小控制功能。
   *          主要用作默认控制器或占位符。
   *          
   *          适用场景：
   *          - 不需要动态调整线程池大小的场景
   *          - 静态配置的线程池
   *          - 简化的线程池实现
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template<typename Pool>
  struct empty_controller
  {
    /*!
     * \brief 构造函数
     * \param policy 大小策略引用（未使用）
     * \param pool 线程池的共享指针（未使用）
     * 
     * \details 空实现，不执行任何操作
     */
    empty_controller(typename Pool::size_policy_type&, shared_ptr<Pool>) {}
  };

  /*!
   * \brief 允许调整大小的大小策略控制器
   *
   * \details 此控制器提供动态调整线程池大小的功能。
   *          它持有对大小策略的引用和线程池的共享指针，
   *          确保在控制器存在期间线程池保持有效。
   *          
   *          特点：
   *          - 支持运行时调整线程数量
   *          - 线程安全的大小调整
   *          - 自动生命周期管理
   *          
   *          适用场景：
   *          - 需要根据负载动态调整的系统
   *          - 资源敏感的应用
   *          - 高性能计算场景
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template< typename Pool >
  class resize_controller
  {
    typedef typename Pool::size_policy_type size_policy_type;
    reference_wrapper<size_policy_type> m_policy; //!< 大小策略的引用包装器
    shared_ptr<Pool> m_pool; //!< 确保线程池在控制器存在期间保持有效的共享指针

  public:
    /*!
     * \brief 构造函数
     * \param policy 大小策略的引用
     * \param pool 线程池的共享指针
     */
    resize_controller(size_policy_type& policy, shared_ptr<Pool> pool)
      : m_policy(policy)
      , m_pool(pool)
    {
    }

    /*!
     * \brief 调整工作线程数量
     * \param worker_count 新的工作线程数量
     * \return 调整成功返回true，否则返回false
     */
    bool resize(size_t worker_count)
    {
      return m_policy.get().resize(worker_count);
    }
  };

  /*!
   * \brief 保持线程数量的大小策略
   *
   * \details 此策略维护固定的线程数量。当工作线程意外终止时，
   *          它会自动创建新的线程来替换。
   *          
   *          特点：
   *          - 维护恒定的线程数量
   *          - 自动替换意外终止的线程
   *          - 支持手动调整大小
   *          - 简单可靠的实现
   *          
   *          适用场景：
   *          - 负载相对稳定的系统
   *          - 需要预定义性能特征的应用
   *          - 资源使用可预测的场景
   *
   * \tparam Pool 线程池的核心类型
   */ 
  template<typename Pool>
  class static_size
  {
    reference_wrapper<Pool volatile> m_pool; //!< 线程池的volatile引用包装器

  public:
    /*!
     * \brief 初始化线程池大小
     * \param pool 线程池引用
     * \param worker_count 初始工作线程数量
     * 
     * \details 设置线程池的初始大小
     */
    static void init(Pool& pool, size_t const worker_count)
    {
      pool.resize(worker_count);
    }

    /*!
     * \brief 构造函数
     * \param pool 线程池的volatile引用
     */
    static_size(Pool volatile & pool)
      : m_pool(pool)
    {}

    /*!
     * \brief 调整工作线程数量
     * \param worker_count 新的工作线程数量
     * \return 调整成功返回true，否则返回false
     */
    bool resize(size_t const worker_count)
    {
      return m_pool.get().resize(worker_count);
    }

    /*!
     * \brief 处理工作线程意外终止
     * \param new_worker_count 当前工作线程数量
     * 
     * \details 当工作线程意外终止时，自动增加一个新线程来替换
     */
    void worker_died_unexpectedly(size_t const new_worker_count)
    {
      m_pool.get().resize(new_worker_count + 1);
    }

    /*!
     * \brief 任务调度回调
     * 
     * \details TODO: 这些函数尚未被调用
     */
    void task_scheduled() {}
    
    /*!
     * \brief 任务完成回调
     * 
     * \details TODO: 这些函数尚未被调用
     */
    void task_finished() {}
  };

} } // namespace boost::threadpool

#endif // THREADPOOL_SIZE_POLICIES_HPP_INCLUDED
